This is a reusable alarm concern for Active Record models. It adds support for the automatic maintenance of Active Job's which are scheduled for the given alarms. On alarm updates the jobs will be canceled and rescheduled. This is supported only for Sidekiq, Delayed Job, resque and the Active Job TestAdapter. (See ActiveJob::Cancel for the list of supported adapters)

• Installation
• Usage
  • Database migration
  • Active Record Model
  • Active Job
• Development
• Code of Conduct
• Contributing
• Releasing

Installation

Add this line to your application's Gemfile:

gem 'alarmable'

And then execute:

$ bundle

Or install it yourself as:

$ gem install alarmable

Usage

Database migration

This concern requires the persistence (and availability) of two properties.

• The first is the JSONB array which holds the alarms. (alarms)
• The seconds is the JSONB array which holds the ids of the scheduled alarm jobs. (alarm_jobs)

$ rails generate migration AddAlarmsAndAlarmJobsToEntity \
  alarms:jsonb alarm_jobs:jsonb

Active Record Model

Furthermore a Active Record model which uses this concern must define the Active Job class which will be scheduled. (alarm_job) The user must also define the base date property of the owning side. (alarm_base_date_property) This base date is mandatory to calculate the correct alarm date/time. When the base date is not set (nil) no new notification job will be enqueued. When the base date is unset on an update, the previously enqueued job will be canceled.

# Your Active Record Model
class Entity < ApplicationRecord
  include Alarmable
  self.alarm_job = NotificationJob
  self.alarm_base_date_property = :start_at
end

The alarms hash needs to be an array in the following format:

[
  {
    "channel": "email",   # email, push, web_notification, etc..
    "before_minutes": 15  # start_at - before_minutes, >= 1

    # [..] you can add custom properties if you like
  }
]

Active Job

The given alarm job class will be scheduled with the following two arguments.

• id - The class/instance id of the record which owns the alarm
• alarm - The alarm hash itself (see the format above)

A suitable alarm job perform method should look like this:

# Your notification job
class NotificationJob < ApplicationJob
  # @param id [String] The entity id
  # @param alarm [Hash] The alarm object
  def perform(id, alarm)
    # Do something special for `alarm.channel` ..
  end
end

Development

After checking out the repo, run make install to install dependencies. Then, run make test to run the tests. You can also run make shell-irb for an interactive prompt that will allow you to experiment.

Code of Conduct

Everyone interacting in the project codebase, issue tracker, chat rooms and mailing lists is expected to follow the code of conduct.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/hausgold/alarmable. Make sure that every pull request adds a bullet point to the changelog file with a reference to the actual pull request.

Releasing

The release process of this Gem is fully automated. You just need to open the Github Actions Release Workflow and trigger a new run via the Run workflow button. Insert the new version number (check the changelog first for the latest release) and you're done.