notify-engine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49f09cd818de4b46ff8276c410d3f9387e01f5452d353fac70059adbf04c56ce
+  data.tar.gz: 512d37c685c49874b7bcb47919aaad4f3ebe382a2c566cefb5474dbeb5a0948f
+SHA512:
+  metadata.gz: 14994f2a931a9475c25e553ea6ced47f0c12c3994b2045a39fa78501c78c537b80cdd1a05b330f061ecb9fb11761d247985089ba7163ed93f4fc03e42809c235
+  data.tar.gz: e79f3abe314da7fe841add18b0ec5cb9fbab2610a1775525138a45860d3dd3c5c86af2d834338078e74399d64ae608336adce4229c12a5f39ce70773bda63332

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-29
+
+### Added
+
+- Convention-over-configuration message dispatch via `Notify.message(:name, **payload)` with `Notify.configure` block for adapter and per-message configuration
+- Filesystem-driven template discovery at `app/notify_templates/<adapter>/<name>.<ext>` with format-agnostic scanning (ERB, Haml, Slim — any registered `ActionView` handler), `_` prefix to disable templates, and `Notify.messages` / `Notify.adapters` introspection
+- Optional payload class compute layer (`Notify::PayloadClass`) with 7-method class-level DSL (`subject`, `email_recipients`, `email_from`, `email_cc`, `email_bcc`, `tg_recipients`, `locals`), static/Proc/block support via `instance_exec`, instance method overrides, and 5-level resolution priority chain
+- ActionMailer-backed email adapter (`Notify::Adapters::Email`) with multipart support, configurable layout and helpers, subject prefix (String or Proc), CC/BCC, per-message from override, and delivery method selection (`deliver_later` default, `deliver_now` override)
+- Test mode with `Notify.test_mode!`, `Notify.deliveries` capture array, and `Notify::TestHelper` providing `assert_notify_dispatched`, `last_notify_delivery`, and `setup_notify_test_mode` — auto-activates in `Rails.env.test?`
+- `ActiveSupport::Notifications` instrumentation events: `notify.message.dispatch`, `notify.adapter.deliver`, `notify.adapter.error`
+- Structured error handling: `Notify::UnknownMessage`, `Notify::MissingRecipients`, `Notify::MissingSubject`, and `Notify::DeliveryError` with aggregated `.adapter_errors` — per-adapter error isolation ensures one failure does not block other adapters
+- Pluggable adapter system via `Notify.register_adapter(:name, klass)` and `Notify::Adapters::Base` contract (`#deliver`, `.template_extensions`) for custom delivery channels
+
+[0.1.0]: https://github.com/lstpsche/notify-engine-gem/releases/tag/v0.1.0

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikita Shkoda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,514 @@
+# notify-engine
+
+Convention-over-configuration multi-channel notification dispatch for Rails.
+
+- Single dispatch interface: `Notify.message(:name, **payload)`
+- Filesystem-driven adapter routing — presence of a template determines which channels fire
+- Optional payload class compute layer for recipient resolution, subject building, and data transformation
+- Pluggable adapters (email built-in, custom adapters via `Notify.register_adapter`)
+- Introspection: `Notify.messages` and `Notify.adapters`
+
+## Installation
+
+Add the gem to your Rails application's Gemfile:
+
+```ruby
+gem "notify-engine"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+**Requires Rails 7.0+.**
+
+## Quick Start
+
+**1. Create a template**
+
+```text
+app/notify_templates/email/stuck_pg_jobs.html.erb
+```
+
+```erb
+<h2>Stuck PgJobs Detected</h2>
+
+<p>The following jobs are stuck:</p>
+
+<ul>
+  <% @pg_jobs.each do |job| %>
+    <li>Job #<%= job.id %> — stuck since <%= job.updated_at %></li>
+  <% end %>
+</ul>
+```
+
+**2. Configure the message**
+
+```ruby
+# config/initializers/notify.rb
+Notify.configure do |config|
+  config.adapters[:email] = {
+    enabled: true,
+    from: "alerts@example.com",
+    delivery_method: :deliver_later
+  }
+
+  config.messages[:stuck_pg_jobs] = {
+    subject: "Stuck PgJobs detected",
+    email_recipients: -> { ENV.fetch("ADMIN_EMAILS", "").split(",") }
+  }
+end
+```
+
+**3. Dispatch**
+
+```ruby
+Notify.message(:stuck_pg_jobs, pg_jobs: stuck_jobs)
+```
+
+That's it. The email adapter picks up the template, resolves recipients and subject from config, and delivers.
+
+## Template Directory Convention
+
+```text
+app/notify_templates/
+├── email/
+│   ├── stuck_pg_jobs.html.erb
+│   ├── stuck_pg_jobs.text.erb      # multipart companion
+│   ├── export_report.html.erb
+│   └── _disabled_message.html.erb  # _ prefix = excluded from registry
+├── telegram/
+│   └── stuck_pg_jobs.md.erb
+├── stuck_pg_jobs.rb                # optional PayloadClass
+└── export_report.rb                # optional PayloadClass
+```
+
+- Each subdirectory of `app/notify_templates/` is an **adapter name**.
+- Files within an adapter directory are **templates**. The base filename (without format and handler extensions) is the **message name**.
+- Files starting with `_` are excluded from the registry (disabled).
+- Multipart templates (`.html.erb` + `.text.erb`) are de-duplicated into a single message and produce a multipart email automatically.
+- Template discovery is **format-agnostic**: any handler registered via `ActionView::Template::Handlers` is supported (ERB, Haml, Slim, etc.).
+- Payload class files live alongside adapter directories, not inside them.
+
+### Introspection
+
+```ruby
+Notify.messages
+# => { export_report: [:email], stuck_pg_jobs: [:email, :telegram] }
+
+Notify.adapters
+# => { email: [:export_report, :stuck_pg_jobs], telegram: [:stuck_pg_jobs] }
+```
+
+Both hashes are sorted alphabetically at all levels. For advanced use, `Notify.registry` provides direct access to the underlying `Notify::Registry` instance.
+
+## Configuration
+
+```ruby
+# config/initializers/notify.rb
+Notify.configure do |config|
+  # Where templates live (relative to Rails.root)
+  config.templates_path = "app/notify_templates" # default
+
+  # Email adapter settings
+  config.adapters[:email] = {
+    enabled: true,                                    # default: true
+    from: "ae@novus.online",                          # default: nil (falls back to ActionMailer default)
+    delivery_method: :deliver_later,                  # default: :deliver_later
+    default_recipients: ["admin@example.com"],        # default: []
+    layout: false,                                    # default: false (or a layout name string)
+    helpers: [],                                      # default: [] (e.g. [MailerHelper])
+    subject_prefix: -> { "[#{Rails.env.upcase}]:" }   # default: nil (String or Proc)
+  }
+
+  # Telegram adapter (architecture-ready, not yet implemented)
+  config.adapters[:telegram] = {
+    enabled: false,
+    bots: []
+  }
+
+  # Per-message overrides (optional — only when you don't use a payload class)
+  config.messages[:stuck_pg_jobs] = {
+    subject: "Stuck PgJobs detected",
+    email_recipients: -> { ENV.fetch("AE_ADMINS_EMAILS", "").split(",") }
+  }
+
+  config.messages[:export_report] = {
+    subject: "ThinkTime export report",
+    email_recipients: -> { ENV.fetch("THINKTIME_ADMIN_EMAIL", "").split(",") }
+  }
+end
+```
+
+## Dispatching Messages
+
+### Bare minimum — everything from config + template
+
+```ruby
+Notify.message(:stuck_pg_jobs, pg_jobs: stuck_jobs)
+```
+
+### Inline override of config defaults
+
+```ruby
+Notify.message(:stuck_pg_jobs,
+  pg_jobs: stuck_jobs,
+  subject: "Custom subject override",
+  email_to: ["override@example.com"]
+)
+```
+
+### Payload class handles everything
+
+```ruby
+Notify.message(:export_report, export_result: result)
+```
+
+### Reserved payload keys
+
+These keys control dispatch behavior and are stripped from template locals:
+
+| Key | Controls |
+|-----|----------|
+| `subject:` | Email subject line |
+| `email_to:` | Email recipients override |
+| `email_from:` | From address override |
+| `email_cc:` | CC recipients |
+| `email_bcc:` | BCC recipients |
+| `tg_bots:` | Telegram bot targets |
+| `delivery_method:` | `:deliver_later` or `:deliver_now` |
+
+## Payload Classes
+
+### Location and naming
+
+Payload classes live at `app/notify_templates/<name>.rb` with the class name `NotifyTemplates::<CamelizedName>` inheriting from `Notify::PayloadClass`.
+
+```text
+app/notify_templates/stuck_pg_jobs.rb → NotifyTemplates::StuckPgJobs
+app/notify_templates/export_report.rb → NotifyTemplates::ExportReport
+```
+
+### Full example
+
+```ruby
+# app/notify_templates/stuck_pg_jobs.rb
+class NotifyTemplates::StuckPgJobs < Notify::PayloadClass
+  subject { "#{@pg_jobs.size} stuck PgJob(s) detected" }
+  email_recipients -> { ENV.fetch("AE_ADMINS_EMAILS", "").split(",") }
+  email_cc ["manager@example.com"]
+  tg_recipients %i[alerts_bot notifier]
+  locals { { pg_jobs: @pg_jobs, detected_at: Time.current } }
+
+  def initialize(**payload)
+    @pg_jobs = payload[:pg_jobs]
+  end
+end
+```
+
+### DSL method semantics
+
+Each DSL method accepts a static value, a Proc/Lambda, or a block:
+
+```ruby
+subject "Static subject"                           # static value
+subject -> { "Dynamic: #{@pg_jobs.size} stuck" }   # Proc — instance_exec'd at dispatch
+subject { "Dynamic: #{@pg_jobs.size} stuck" }      # block — instance_exec'd at dispatch
+```
+
+Blocks and Procs are `instance_exec`'d on the payload class instance at dispatch time (not at class load), so they have access to instance variables set in `initialize`.
+
+### Instance method override
+
+Define an instance method with the same name to take absolute precedence over the DSL declaration:
+
+```ruby
+class NotifyTemplates::StuckPgJobs < Notify::PayloadClass
+  subject { "#{@pg_jobs.size} stuck PgJob(s)" }
+
+  def initialize(**payload)
+    @pg_jobs = payload[:pg_jobs]
+  end
+
+  def subject
+    prefix = @pg_jobs.size > 10 ? "URGENT" : "Warning"
+    "#{prefix}: #{@pg_jobs.size} stuck PgJob(s)"
+  end
+end
+```
+
+### Available DSL methods
+
+| Method | Description |
+|--------|-------------|
+| `subject` | Email subject line |
+| `email_recipients` | To: addresses (coerced to array) |
+| `email_from` | From: address override |
+| `email_cc` | CC: addresses |
+| `email_bcc` | BCC: addresses |
+| `tg_recipients` | Telegram bot name(s) |
+| `locals` | Template variables hash |
+
+### Resolution priority
+
+When resolving `subject`, `recipients`, and `locals`, the first non-nil value wins:
+
+1. **Payload class instance method** — runtime logic
+2. **Payload class DSL declaration** — `instance_exec`'d at dispatch
+3. **Inline kwargs** in `Notify.message()` call
+4. **Per-message config** in initializer
+5. **Global adapter defaults** in initializer
+
+### When no payload class exists
+
+- `locals` = raw `**payload` minus reserved keys
+- Recipients and subject come from inline kwargs or initializer config
+- If neither provides recipients → raises `Notify::MissingRecipients`
+- If neither provides a subject (email) → raises `Notify::MissingSubject`
+
+## Email Adapter
+
+### Template rendering
+
+Templates at `app/notify_templates/email/<name>.<format>.<handler>` are rendered by an internal ActionMailer subclass. Template locals are set as instance variables (`@var`) on the mailer, following ActionMailer convention.
+
+### Multipart emails
+
+If both `.html.erb` and `.text.erb` exist for the same message, ActionMailer automatically produces a multipart email.
+
+### Subject prefix
+
+`config.adapters[:email][:subject_prefix]` accepts a String or Proc, prepended to all email subjects:
+
+```ruby
+config.adapters[:email][:subject_prefix] = -> { "[#{Rails.env.upcase}]:" }
+# Subject "Stuck PgJobs" becomes "[PRODUCTION]: Stuck PgJobs"
+```
+
+When `nil` or empty, no prefix is applied.
+
+### Layout
+
+`config.adapters[:email][:layout]` defaults to `false` (no layout). Set to a layout name string to wrap templates in a layout from `app/views/layouts/`:
+
+```ruby
+config.adapters[:email][:layout] = "notify_mailer"
+```
+
+### Helpers
+
+`config.adapters[:email][:helpers]` — array of helper modules available in templates:
+
+```ruby
+config.adapters[:email][:helpers] = [MailerHelper]
+```
+
+### CC/BCC
+
+Set via payload class DSL (`email_cc`, `email_bcc`), per-message config, or inline kwargs:
+
+```ruby
+Notify.message(:stuck_pg_jobs, pg_jobs: jobs, email_cc: ["manager@example.com"])
+```
+
+### From override
+
+Resolution: payload class `email_from` → per-message config → adapter config `from:` → ActionMailer default.
+
+### Delivery method
+
+Defaults to `:deliver_later`. Override per-adapter, per-message, or inline:
+
+```ruby
+# Per-message config
+config.messages[:stuck_pg_jobs] = {
+  subject: "Stuck PgJobs",
+  email_recipients: ["admin@example.com"],
+  delivery_method: :deliver_now
+}
+
+# Inline
+Notify.message(:stuck_pg_jobs, pg_jobs: jobs, delivery_method: :deliver_now)
+```
+
+### Recipient arrayification
+
+All recipient values are coerced to arrays — passing a single string works fine.
+
+## Test Mode
+
+### Activation
+
+Test mode auto-activates in `Rails.env.test?` via an engine initializer. For manual activation:
+
+```ruby
+Notify.test_mode!
+```
+
+Check status with `Notify.test_mode?`. Deactivate with `Notify.reset_test_mode!`.
+
+### Captured deliveries
+
+When test mode is active, `Notify.message` captures dispatches to `Notify.deliveries` instead of delivering. Each entry is a hash:
+
+```ruby
+{
+  name: :stuck_pg_jobs,
+  adapters: [:email],
+  payload: { pg_jobs: [...] },
+  resolved: {
+    subject: "3 stuck PgJob(s) detected",
+    recipients: { email: ["admin@example.com"] },
+    locals: { pg_jobs: [...] }
+  }
+}
+```
+
+The `recipients` hash is keyed by adapter symbol because recipient formats differ across adapters.
+
+### RSpec setup
+
+```ruby
+# spec/support/notify.rb (or spec/rails_helper.rb)
+RSpec.configure do |config|
+  config.include Notify::TestHelper
+  config.before(:each) { Notify.deliveries.clear }
+end
+```
+
+### Assertion methods
+
+| Method | Description |
+|--------|-------------|
+| `assert_notify_dispatched(:name, count:, to:)` | Verify a message was dispatched (optionally check count and recipients) |
+| `last_notify_delivery` | Shorthand for `Notify.deliveries.last` |
+| `setup_notify_test_mode` | Activate test mode and clear deliveries |
+
+### Full test example
+
+```ruby
+RSpec.describe "Stuck PgJobs notification" do
+  it "dispatches to admin emails" do
+    Notify.message(:stuck_pg_jobs, pg_jobs: [double(id: 1, updated_at: Time.current)])
+
+    assert_notify_dispatched(:stuck_pg_jobs, count: 1)
+    assert_notify_dispatched(:stuck_pg_jobs, to: ["admin@example.com"])
+
+    delivery = last_notify_delivery
+    expect(delivery[:resolved][:subject]).to include("stuck")
+    expect(delivery[:resolved][:locals][:pg_jobs]).to be_present
+  end
+end
+```
+
+## Instrumentation
+
+The dispatcher emits `ActiveSupport::Notifications` events:
+
+| Event | Payload | When |
+|-------|---------|------|
+| `notify.message.dispatch` | `{ message_name:, adapters: }` | On dispatch entry |
+| `notify.adapter.deliver` | `{ message_name:, adapter:, to: }` | Per-adapter delivery |
+| `notify.adapter.error` | `{ message_name:, adapter:, error: }` | On adapter failure |
+
+### Subscriber example
+
+```ruby
+ActiveSupport::Notifications.subscribe("notify.message.dispatch") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.info(
+    "[Notify] Dispatched #{event.payload[:message_name]} to #{event.payload[:adapters]}"
+  )
+end
+```
+
+## Custom Adapters
+
+### Adapter contract
+
+Custom adapters inherit from `Notify::Adapters::Base` and implement two methods:
+
+```ruby
+class MySlackAdapter < Notify::Adapters::Base
+  def deliver(message_name:, to:, subject:, locals:, template_path:, options: {})
+    # Deliver the notification via your channel.
+    # `to` is the resolved recipients array.
+    # `locals` is the resolved template variables hash.
+    # `template_path` is the Pathname to the adapter's template directory.
+  end
+
+  def self.template_extensions
+    # Return an array of file extensions this adapter recognizes.
+    # Used by the registry to discover templates.
+    %i[text.erb md.erb]
+  end
+end
+```
+
+### Registration
+
+```ruby
+# config/initializers/notify.rb
+Notify.register_adapter(:slack, MySlackAdapter)
+```
+
+Once registered, drop templates in `app/notify_templates/slack/` and they auto-route on dispatch.
+
+## Error Handling
+
+| Error | Raised when |
+|-------|-------------|
+| `Notify::UnknownMessage` | `Notify.message(:nonexistent)` — no templates found for this name |
+| `Notify::MissingRecipients` | No recipients resolvable for an adapter |
+| `Notify::MissingSubject` | No subject resolvable for the email adapter |
+| `Notify::DeliveryError` | ALL adapters fail (access individual errors via `.adapter_errors`) |
+
+### Adapter error isolation
+
+When multiple adapters handle a message, one adapter failing does not block the others. Only if **all** adapters fail does `Notify::DeliveryError` propagate to the caller.
+
+### Payload class initialization errors
+
+If a payload class raises during `initialize` or any resolution method, the error is caught and logged. The dispatcher falls back to raw payload mode for that adapter.
+
+## Out of Scope (MVP)
+
+The following are explicitly not part of the 0.1.0 release:
+
+- Telegram Bot API delivery (architecture supports it, implementation deferred)
+- Delivery tracking / persistence
+- User preferences / opt-out
+- Template previews (à la `ActionMailer::Preview`)
+- Retry logic (delegated to ActiveJob/Sidekiq via `deliver_later`)
+- Admin UI
+- I18n locale switching
+- Attachments
+- Rate limiting / deduplication
+- Migration tooling (manual conversion required)
+- Rails generators (`rails g notify:template`)
+
+## Development
+
+```sh
+git clone https://github.com/lstpsche/notify-engine-gem.git
+cd notify-engine-gem
+bundle install
+```
+
+Run tests:
+
+```sh
+bundle exec rspec
+```
+
+Build the gem:
+
+```sh
+gem build notify-engine.gemspec
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/notify/adapters/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Notify
+  module Adapters
+    class Base
+      def deliver(message_name:, to:, subject:, locals:, template_path:, options: {})
+        raise Notify::NotImplementedError, "#{self.class}#deliver must be implemented"
+      end
+
+      def self.template_extensions
+        raise Notify::NotImplementedError, "#{name || self}.template_extensions must be implemented"
+      end
+    end
+  end
+end

data/lib/notify/adapters/email.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "action_view"
+
+module Notify
+  module Adapters
+    class Email < Base
+      def deliver(message_name:, to:, subject:, locals:, template_path:, options: {})
+        subject = apply_subject_prefix(subject)
+        from = options[:from]
+        cc = options[:cc]
+        bcc = options[:bcc]
+        delivery_method = options[:delivery_method] || email_config[:delivery_method] || :deliver_later
+
+        configure_mailer!
+
+        message = Notify::Mailer.dispatch(
+          message_name,
+          locals: locals,
+          to: Array(to),
+          subject: subject,
+          from: from,
+          cc: cc,
+          bcc: bcc,
+          template_path: template_path.to_s
+        )
+
+        case delivery_method.to_sym
+        when :deliver_now
+          message.deliver_now
+        else
+          message.deliver_later
+        end
+      end
+
+      def self.template_extensions
+        formats = begin
+          ActionView::Template::Types.symbols
+        rescue StandardError
+          %i[html text]
+        end
+        handlers = ActionView::Template::Handlers.extensions
+
+        extensions = []
+        formats.each do |format|
+          handlers.each do |handler|
+            extensions << :"#{format}.#{handler}"
+          end
+        end
+        handlers.each { |h| extensions << h }
+
+        extensions.uniq
+      end
+
+      private
+
+      def email_config
+        Notify.config.adapters[:email] || {}
+      end
+
+      def apply_subject_prefix(subject)
+        prefix = email_config[:subject_prefix]
+        return subject if prefix.nil?
+
+        prefix_str = prefix.respond_to?(:call) ? prefix.call : prefix.to_s
+        return subject if prefix_str.nil? || prefix_str.to_s.strip.empty?
+
+        "#{prefix_str} #{subject}"
+      end
+
+      def configure_mailer!
+        configure_layout!
+        configure_helpers!
+      end
+
+      def configure_layout!
+        Notify::Mailer.layout(email_config[:layout] || false)
+      end
+
+      def configure_helpers!
+        helpers = email_config[:helpers]
+        return unless helpers.is_a?(Array) && helpers.any?
+
+        helpers.each { |helper_module| Notify::Mailer.helper(helper_module) }
+      end
+    end
+  end
+end